Autogenerated HTML docs for v1.1.6-g1a5c3
diff --git a/cvs-migration.html b/cvs-migration.html index 50f4653..0ee0488 100644 --- a/cvs-migration.html +++ b/cvs-migration.html
@@ -263,124 +263,185 @@ </div> <div id="preamble"> <div class="sectionbody"> -<p>Ok, so you're a CVS user. That's ok, it's a treatable condition, and the -first step to recovery is admitting you have a problem. The fact that -you are reading this file means that you may be well on that path -already.</p> -<p>The thing about CVS is that it absolutely sucks as a source control -manager, and you'll thus be happy with almost anything else. git, -however, may be a bit <em>too</em> different (read: "good") for your taste, and -does a lot of things differently.</p> -<p>One particular suckage of CVS is very hard to work around: CVS is -basically a tool for tracking <em>file</em> history, while git is a tool for -tracking <em>project</em> history. This sometimes causes problems if you are -used to doing very strange things in CVS, in particular if you're doing -things like making branches of just a subset of the project. git can't -track that, since git never tracks things on the level of an individual -file, only on the whole project level.</p> -<p>The good news is that most people don't do that, and in fact most sane -people think it's a bug in CVS that makes it tag (and check in changes) -one file at a time. So most projects you'll ever see will use CVS -<em>as if</em> it was sane. In which case you'll find it very easy indeed to -move over to git.</p> -<p>First off: this is not a git tutorial. See -<a href="tutorial.html">Documentation/tutorial.txt</a> for how git -actually works. This is more of a random collection of gotcha's -and notes on converting from CVS to git.</p> -<p>Second: CVS has the notion of a "repository" as opposed to the thing -that you're actually working in (your working directory, or your -"checked out tree"). git does not have that notion at all, and all git -working directories <em>are</em> the repositories. However, you can easily -emulate the CVS model by having one special "global repository", which -people can synchronize with. See details later, but in the meantime -just keep in mind that with git, every checked out working tree will -have a full revision control history of its own.</p> +<p>So you're a CVS user. That's ok, it's a treatable condition. The job of +this document is to put you on the road to recovery, by helping you +convert an existing cvs repository to git, and by showing you how to use a +git repository in a cvs-like fashion.</p> +<p>Some basic familiarity with git is required. This +<a href="tutorial.html">tutorial introduction to git</a> should be sufficient.</p> +<p>First, note some ways that git differs from CVS:</p> +<ul> +<li> +<p> +Commits are atomic and project-wide, not per-file as in CVS. +</p> +</li> +<li> +<p> +Offline work is supported: you can make multiple commits locally, + then submit them when you're ready. +</p> +</li> +<li> +<p> +Branching is fast and easy. +</p> +</li> +<li> +<p> +Every working tree contains a repository with a full copy of the + project history, and no repository is inherently more important than + any other. However, you can emulate the CVS model by designating a + single shared repository which people can synchronize with; see below + for details. +</p> +</li> +</ul> </div> </div> <h2>Importing a CVS archive</h2> <div class="sectionbody"> -<p>Ok, you have an old project, and you want to at least give git a chance -to see how it performs. The first thing you want to do (after you've -gone through the git tutorial, and generally familiarized yourself with -how to commit stuff etc in git) is to create a git'ified version of your -CVS archive.</p> -<p>Happily, that's very easy indeed. git will do it for you, although git -will need the help of a program called "cvsps":</p> -<div class="literalblock"> +<p>First, install version 2.1 or higher of cvsps from +<a href="http://www.cobite.com/cvsps/">http://www.cobite.com/cvsps/</a> and make +sure it is in your path. The magic command line is then</p> +<div class="listingblock"> <div class="content"> -<pre><tt>http://www.cobite.com/cvsps/</tt></pre> +<pre><tt>$ git cvsimport -v -d <cvsroot> -C <destination> <module></tt></pre> </div></div> -<p>which is not actually related to git at all, but which makes CVS usage -look almost sane (ie you almost certainly want to have it even if you -decide to stay with CVS). However, git will want <em>at least</em> version 2.1 -of cvsps (available at the address above), and in fact will currently -refuse to work with anything else.</p> -<p>Once you've gotten (and installed) cvsps, you may or may not want to get -any more familiar with it, but make sure it is in your path. After that, -the magic command line is</p> -<div class="literalblock"> -<div class="content"> -<pre><tt>git cvsimport -v -d <cvsroot> -C <destination> <module></tt></pre> -</div></div> -<p>which will do exactly what you'd think it does: it will create a git -archive of the named CVS module. The new archive will be created in the -subdirectory named <destination>; it'll be created if it doesn't exist. -Default is the local directory.</p> -<p>It can take some time to actually do the conversion for a large archive -since it involves checking out from CVS every revision of every file, -and the conversion script is reasonably chatty unless you omit the <em>-v</em> -option, but on some not very scientific tests it averaged about twenty -revisions per second, so a medium-sized project should not take more -than a couple of minutes. For larger projects or remote repositories, -the process may take longer.</p> -<p>After the (initial) import is done, the CVS archive's current head -revision will be checked out — thus, you can start adding your own -changes right away.</p> -<p>The import is incremental, i.e. if you call it again next month it'll -fetch any CVS updates that have been happening in the meantime. The -cut-off is date-based, so don't change the branches that were imported -from CVS.</p> -<p>You can merge those updates (or, in fact, a different CVS branch) into -your main branch:</p> -<div class="literalblock"> -<div class="content"> -<pre><tt>git resolve HEAD origin "merge with current CVS HEAD"</tt></pre> -</div></div> -<p>The HEAD revision from CVS is named "origin", not "HEAD", because git -already uses "HEAD". (If you don't like <em>origin</em>, use cvsimport's -<em>-o</em> option to change it.)</p> +<p>This puts a git archive of the named CVS module in the directory +<destination>, which will be created if necessary. The -v option makes +the conversion script very chatty.</p> +<p>The import checks out from CVS every revision of every file. Reportedly +cvsimport can average some twenty revisions per second, so for a +medium-sized project this should not take more than a couple of minutes. +Larger projects or remote repositories may take longer.</p> +<p>The main trunk is stored in the git branch named <tt>origin</tt>, and additional +CVS branches are stored in git branches with the same names. The most +recent version of the main trunk is also left checked out on the <tt>master</tt> +branch, so you can start adding your own changes right away.</p> +<p>The import is incremental, so if you call it again next month it will +fetch any CVS updates that have been made in the meantime. For this to +work, you must not modify the imported branches; instead, create new +branches for your own changes, and merge in the imported branches as +necessary.</p> </div> -<h2>Emulating CVS behaviour</h2> +<h2>Development Models</h2> <div class="sectionbody"> -<p>So, by now you are convinced you absolutely want to work with git, but -at the same time you absolutely have to have a central repository. -Step back and think again. Okay, you still need a single central -repository? There are several ways to go about that:</p> -<ol> -<li> -<p> -Designate a person responsible to pull all branches. Make the -repository of this person public, and make every team member -pull regularly from it. -</p> -</li> -<li> -<p> -Set up a public repository with read/write access for every team -member. Use "git pull/push" as you used "cvs update/commit". Be -sure that your repository is up to date before pushing, just -like you used to do with "cvs commit"; your push will fail if -what you are pushing is not up to date. -</p> -</li> -<li> -<p> -Make the repository of every team member public. It is the -responsibility of each single member to pull from every other -team member. -</p> -</li> -</ol> +<p>CVS users are accustomed to giving a group of developers commit access to +a common repository. In the next section we'll explain how to do this +with git. However, the distributed nature of git allows other development +models, and you may want to first consider whether one of them might be a +better fit for your project.</p> +<p>For example, you can choose a single person to maintain the project's +primary public repository. Other developers then clone this repository +and each work in their own clone. When they have a series of changes that +they're happy with, they ask the maintainer to pull from the branch +containing the changes. The maintainer reviews their changes and pulls +them into the primary repository, which other developers pull from as +necessary to stay coordinated. The Linux kernel and other projects use +variants of this model.</p> +<p>With a small group, developers may just pull changes from each other's +repositories without the need for a central maintainer.</p> +</div> +<h2>Emulating the CVS Development Model</h2> +<div class="sectionbody"> +<p>Start with an ordinary git working directory containing the project, and +remove the checked-out files, keeping just the bare .git directory:</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ mv project/.git /pub/repo.git +$ rm -r project/</tt></pre> +</div></div> +<p>Next, give every team member read/write access to this repository. One +easy way to do this is to give all the team members ssh access to the +machine where the repository is hosted. If you don't want to give them a +full shell on the machine, there is a restricted shell which only allows +users to do git pushes and pulls; see <a href="git-shell.html">git-shell(1)</a>.</p> +<p>Put all the committers should in the same group, and make the repository +writable by that group:</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ chgrp -R $group repo.git +$ find repo.git -mindepth 1 -type d |xargs chmod ug+rwx,g+s +$ GIT_DIR=repo.git git repo-config core.sharedrepository true</tt></pre> +</div></div> +<p>Make sure committers have a umask of at most 027, so that the directories +they create are writable and searchable by other group members.</p> +<p>Suppose this repository is now set up in /pub/repo.git on the host +foo.com. Then as an individual commiter you can clone the shared +repository:</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git clone foo.com:/pub/repo.git/ my-project +$ cd my-project</tt></pre> +</div></div> +<p>and hack away. The equivalent of <tt>cvs update</tt> is</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git pull origin</tt></pre> +</div></div> +<p>which merges in any work that others might have done since the clone +operation.</p> +<div class="admonitionblock"> +<table><tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +<p>The first <tt>git clone</tt> places the following in the +<tt>my-project/.git/remotes/origin</tt> file, and that's why the previous step +and the next step both work.</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>URL: foo.com:/pub/project.git/ my-project +Pull: master:origin</tt></pre> +</div></div> +</td> +</tr></table> +</div> +<p>You can update the shared repository with your changes using:</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git push origin master</tt></pre> +</div></div> +<p>If someone else has updated the repository more recently, <tt>git push</tt>, like +<tt>cvs commit</tt>, will complain, in which case you must pull any changes +before attempting the push again.</p> +<p>In the <tt>git push</tt> command above we specify the name of the remote branch +to update (<tt>master</tt>). If we leave that out, <tt>git push</tt> tries to update +any branches in the remote repository that have the same name as a branch +in the local repository. So the last <tt>push</tt> can be done with either of:</p> +<div class="listingblock"> +<div class="content"> +<pre><tt>$ git push origin +$ git push repo.shared.xz:/pub/scm/project.git/</tt></pre> +</div></div> +<p>as long as the shared repository does not have any branches +other than <tt>master</tt>.</p> +<div class="admonitionblock"> +<table><tr> +<td class="icon"> +<div class="title">Note</div> +</td> +<td class="content"> +<p>Because of this behaviour, if the shared repository and the developer's +repository both have branches named <tt>origin</tt>, then a push like the above +attempts to update the <tt>origin</tt> branch in the shared repository from the +developer's <tt>origin</tt> branch. The results may be unexpected, so it's +usually best to remove any branch named <tt>origin</tt> from the shared +repository.</p> +</td> +</tr></table> +</div> +</div> +<h2>Advanced Shared Repository Management</h2> +<div class="sectionbody"> +<p>Git allows you to specify scripts called "hooks" to be run at certain +points. You can use these, for example, to send all commits to the shared +repository to a mailing list. See <a href="hooks.txt">Hooks used by git</a>.</p> +<p>You can enforce finer grained permissions using update hooks. See +<a href="howto/update-hook-example.txt">Controlling access to branches using +update hooks</a>.</p> </div> <h2>CVS annotate</h2> <div class="sectionbody"> @@ -518,7 +579,7 @@ </div> <div id="footer"> <div id="footer-text"> -Last updated 06-Jan-2006 17:12:56 PDT +Last updated 30-Jan-2006 23:10:24 PDT </div> </div> </body>
